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1.0 INTRODUCTION 

1.1 DESIGN OBJECTIVES 



1.0 INIRODU£lIOiJ 



The IPL Data Management system consists of operating system 
procedures which have the general resDonsibi I ity for managing 
files* Deripheral devices and removable storage volumes and for 
moving data between the peripheral devices and central memory. 
The Data Management system consists of five major functional 
areas: Volume Management, File Management, Record Management* 
Block Management and Device Drivers. Data Base Control 
Procedures provide a higher level capability than the Data 
Management system and are described in separate specifications. 

Volume Management procedures operate inclose cooperation 
with Job Management procedures to control the scheduling of 
peripheral devices and attachment/detachment of removable storage 
volumes to/ from peripheral devices. 

File Management procedures have the general responsibility 
for all operations necessary to prepare a file for processing and 
for all operations necessary to clean up after file processing is 
complete. These operations fall into the general categories of 
file definition and creation, file catalog management and 
execution- timp file management. 

Record Management procedures have the general responsibility 

for providing storage and retrieval of records in a variety of 

file organizations. They are the primary execution-time, 
interface oetween the user and a file. 

Block Management procedures have the general responsibility 
for coordinating the movement of data blocks between the user and 
a file and for routing external signals back to the user. Block 
Management procedures also control the logging of abnormal 
conditions detected by the peripheral system. 

Device Drivers have the general responsibility for managing 
the communication with the hardware/software components of the 
peripheral configuration, for first- level error recovery and for 
capturing all signals coming in from the peripheral 
configuration. Device Drivers are described in separate 
specif icat ions. 
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1.1 DESIGN OBJECT IVES 



A number of assumptions and objectives influence both the 
features that are present in the Data Management system and the 
internal structure that supports the features. Some of the more 
important of these are discussed in the following paragraphs! 



The Data Management system 
imposed by ANSI standards. 



must meet . the requirements 



o The Data Management system must support the requirements 
imposed by members of the IPL product set u nles s a 
specific requirement is unique to only one product set 
member. In that case, some Judgement may be applied to 
determine whether the requirement should be satisfied by 
the Data Management system directly or if the product set 
member should/could satisfy the requirement using some 
combination of existing Data Management facilities. 

o The Data Management system must provide support for 
sharing of files among multiple users, each of whom may be 
updating the file. 

o The Data Management system must provide the capability for 
an installation to interpose a security subsystem between 
users and the Data Management System. 

o The Data Management system must be capable of effectively 
using extremely large central memories without design 
change. 

o The Data Management system must be capable of operating on 
a system which ha*s a central memory of 256K bytes. 

o The Data Management system must be capable of effectively 
supporting very large mass storage files (exceeding 
4x10**9 bytes) . 

o The Data Management system must efficiently support a 
large installation which operates in a multiprogramming 
and multiprocessing mode with on-line storage on the order 
of one billion bytes, on-line files totalling on the order 
of ten thousand, and some form of off-line or removable 
storage totalling several times the capacity of the 
on- I ine storage. 

o The Data Management system must permit tape and disk 
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1.0 INTRODUCTION 
1.2 TERMINOLOGY 



storage volumes to be easily interchanged among IPL 
installations. 

The Data Management system must support terminals in a 
manner consistent with support of other hardware types. 
To the maximum practical extent, IPL programs should be 
able to deal with terminals and unit record devices as 
sequentially organized files. 
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Record - A record is the unit of addressability of a file through 
a Record Management procedure. A record consists of a fixed 
or variable length byte string whose content is generally 
known only to the user. The only interpretation of record 
content by a Record Management procedure is on fields which 
have been defined by the user to contain keys to be used for 
subsequent addressing. Five record types are supported, four 
of which conform to ANSI taoe interchange standards. The 
fifth is the default system format. 

Physical Record - A physical record is the smallest unit of data 
transfer between a device and memory for which a device 
status is available. Cards, print lines, tape records and 
disk sectors are examples of physical records. 

Block - A block is the unit of addressability of a file through a 
Block Management procedure and is also the unit of transfer 
between central memory and a file. The maximum block size is 
fixed for a file at the time the file is first defined. 
Block Management procedures are unaware of the content of a 
block and treat it as an unformatted byte string to be mapped 
onto a peripheraJ recording device. The mapping is done in 
one of three basic ways, depending on the characteristics of 
the recording device. 



1. 



3. 
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is on magnetic tape, then 
as one physical tape record, 
vary in length up to the 



each block is 

Blocks within a 

usei — specified 



is on a mass storage device, each block begins 
ical record (sector) boundary and continues 
s many contiguous sectors as necessary. Blocks 

file are mapped as fixed-length units of 
hich may contain variable amounts of data, 
e i s on a unit record device, each block begins 
ical record (card, print line, etc.) boundary 
inues through as many physical records as 
If blocks contain multiple records, the filling 
ing of blocks from/to the unit record device is 
hed by device drivers. 



File - Dependinq on the users level of interface to the Data 
Management system, a file may be viewed in the following 
ways* 
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1,0 INTRODUCTION 
1.2 TERMINOLOGY 



1. File Management Level - A file consists of a peripheral 
device or a region of storage on a volume. 

2. Record Management Level - A file consists of a set of 
records addressable by key, by ordinal* or by file 
address. 

3. Block Management Level - A file consists of a set of 
blocks addressable by block numbers. 

k. Segment Level - A file consists of a segment of virtual 
memory addressable by segment number and byte offset. 

File Control Block - A File Control Block is a symbolically 
addressable table in a System LNS segment that contains a 
description of the logical properties of a file. A File 
Control Block is the primary means through wliich parameters 
are passed from the user to the File Management procedures. 

Permanent File - A permanent file is a mass storage file for 
which a description of its logical and physical 
characteristics has been recorded in a catalog. Permanent 
files survive beyond the life of the job in which they are 
created. 

Temporary File - A temporary file is one for which a description 
of its logical and physical characteristics exists only in 
the File Control Block and internal system tables. Temporary 
files exist no longer than the life of the Job in which they 
are created. A temDorary mass storage file may be converted 
to a permanent file. 

File Address -. Each time a record is stored in or retrieved from 
a mass storage file» the Record Management procedures return 
a file address which uniquely identifies the record. Users 
may save this file address and use it later to retrieve the 
record. The file address of a record remains constant until 
the record is deleted or the file is reorganized. 

Device - A device is an addressable unit in the peripheral 
configuration that can be acquired for use by a job. 
Examdes of devices are tape drives* disk storage drives* 
card readers* punches and printers. 

Device Control Block - A Device Control Block is a symbolically 
addressable table in a system LNS segment that contains a 
description of a device. 

Volume - A volume is a unit of external storage such as a 
fixed-head disk, a drum* a disk pack or a reel of magnetic 
tape. Each volume of a given type is identified by a 
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six-character alphanumeric serial number which is recorded 
(magnetically) in a volume label and is also printed 
externally on the volume. Magnetic tapes which are defined 
to have non-standard or no labejs are accomodated as 
except ions. 

Volume Set - A volume set is a logically related set of volumes 
which contains a f i le or a set of files. A single file 
catalog exists for each mass storage volume set. Files can 
not span volume sets. A volume cannot be a member of more 
than one volume set. A mass storage volume set cannot be 
partially on-line if files are being processed on it. 

Volume Set Control Block - A Volume Set Control Block is a 
symbolically addressable table in a System LNS segment that 
contains a description of a volume set. 

System Volume Set - The System Volume Set is a mass storage 
volume set that is permanently on-line and is implicitly 
attached to every job. It provides the default residency for 
all permanent and temporary mass storage files. Its size is 
selectable by an installation and must consist of at least 
one volume. 

Labels - Two types of labels are processed by the Data Management 
system? volume labels and file labels. Standard volume 
labels for magnetic tape conform to ANSI interchange 
standards. Standard volume labels for mass storage carry 
additional information required to describe the volume. 
Standard file labels for magnetic tape conform to ANSI 
interchange standards. Labels for mass storage files are 
recorded in volume set catalogs and are not compatible with 
any known system. The Data Management system also supports 
tapes with non-standard or no labels. 
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1.0 INTRODUCTION 

1.3 INCOMPLETE FUNCTIONAL AREAS 



1-3 INCOMPLETE FUNCTION AL AREA S 



A number of functional areas are either incompletely 
specified or are relatively unstable at this date. In either 
case, the information relating to these areas in this issue of 
the GDS can be expected to change, either because information is 
replacing an absence of information or because stable information 
is replacing unstable information. GDS changes which perform the 
reverse are not planned. Relevant functional areas are described 
in the following paragraohs. 

Terminal Processing - A consistent interface between programs and 
terminals* the general caDabilities of various software 
components (message control systems* front-end processors* 
communication controllers? device drivers* block and record 
management procedures? etc.) and the hardware components of 
the peripheral configuration are not yet SDecified. 

Hardware-Deoendent Interfaces - Most periDheral hardware 
characteristics visible through the interfaces discussed in 
this issue of the GDS are based on general hardware 
characteristics rather than on IPL hardware specifications. 
As conrol ler and device characteristics for IPL become 
specified, these areas of the GDS can be expected to change* 

Management of Output Streams - The command language chapter of 
the GDS discusses a stream capability which permits a 
many-to-one and one-to-many relationship between streams and 
files. Because of its suitability for logging and handling 
the many sy stem-supD I ied job files, this caDability is 
intended to be eventually incorporated into the Data 
Management System. We haven't had time to do it yet. 

Tape Label Processing - This area is not yet well defined. Some 
resolution of Cobol requirements and a more complete 
specification of tape label processing is expected to occur 
during the next few months. 

Generation Number Processing - The reauirement for this facility 
is not deary defined. As it becomes better defined, the GDS 
will be modified to reflect the new requirements. 

File-Program Relationships - The general use of the execute 
attribute on files, the use of Library file organization, the 
use and meaning of opening a file for execution, the 
assigning of execute ring brackets to files and the exact 
relationship between files and segments are all undergoing 
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review at the present time. The capabilities described in 
this GDS are not necessarily expected to change but the 
method of achieving the capabilities may change. 

File Sharing - Topics that do not yet appear to have stabilized 
include: a concise definition of the relationships among 
jobs, control points, instances of open and locked blocks or 
records? proper resolution of deadlocks' and a concise 
description of valid concurrent file sharing selections. 



Device-Volume Sharing - Clarification of the 
between the Job Management schedul ing 
device-volume-file requests will occur over 
months • 
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2.0 BASIC CONCEPTS 

2.1 FILE DEFINITION 



2 . BASIC CONCEPTS 



The following topics are judged to be sufficiently 
significant to justify their apnearance in this section rather 
than the section on terminology. 



2.1 FILE DEFINITION 



The File Control Block provides the primary interface 
through which a user supplies the definition of a file. A File 
Control Block* which may be constructed either by direct use of 
LNS requests or by use of the Pile Management FM#DEFINE_FILE 
request, must exist in a System LNS segment before a file can be 
referenced . 
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In summary, the following items are important* 

a) a File Control Block must exist before a file can be 
referenced 

b) cataloged values can replace any existing File Control 
B I ock va lues 

c) values suDDlied through LNS requests can replace any 
existing File Control Block values 
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d) values supplied through the FM#DEFINE_FILE request can 
replace only null values 

e) no File Control Block fields can be directly modified by 
the user after the file is created (new mass storage 
files), attached (existing mass storage files) or opened 
(non-mass storage files). 

The precedence rules are based on the assumption the file 
definitions will be supplied through the System Command Language 
by use" of LNS requests and through compile-time declarations by 
use of the FM//DEFINE_FILE request. This permits compile-time 
declarations to be overriden by the user at execution time, 
through use of the System Command Languaoe, but assures that the 
cataloged description of the file will override both of the 
others • 
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2.0 BASIC CONCEPTS 
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2.2 FILE SECURITY 


1 
2 


File security relies heavily on the validation of a user's 


3 

4 


identity at the time the user logs into the system. The primary 


5 


objective is to concentrate on verifying that the current user 


6 


is, in fact, who he says he is, then rely on th3t verification to 


7 


control access to files. 


8 

9 

10 


A second asoect of file security relates to the interna! 


structure of IPLOS comDonents and to the use of the IPL memory 


ii 


protection hardware. Given that the owner of a file is entitled 


12 


to do anything he wishes with the file, the major problem is to 


13 


prevent others from doing things the owner does not want them to 


14 


do. By (a) allowing the owner to specify the tyoe of access he 


15 


will oermit others to have (e.g.* shared read-only access through 


16 


a specific File Access Procedure which runs at a -privileged 


17 


subsystem level)* then (b) placing the data and related control 


18 


tables into memory segments which are not directly accessable to 


19 


the user, then (c) forcing access requests to be made through 


20 


controlled entry points and verifying that all entry points are 


21 


followed in the prooer order t the specified level of security is 


22 


achieved without unreasonable performance penalties. 


23 




24 


The use of a File Access Procedure, discussed as a separate 


25 


topic in this section, permits the owner of a permanent mass 


26 


storaje file to build additional security checking if needed 


27 


since the Data Management software forces e\/Qry request against 


28 


the file to be routed through the File Access Procedure before 


29 


being processed by the system. 
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2.0 9ASIC CONCEPTS 
2.5 FILE SHARING 



Z.i* ACCESS CONTROL LISTS 



The owner of a permanent mass storage file may generate an 
Access Control List which allows others to access the file and 
specifies in what manner they may acess it. Each entry in an 
Access Control List has three components' a user identifier} an 
account identifier, and the access rights allowed for this 
combination of user identifier and account identifier. By 
convention, a null value for either of the first two components 
is defined to mean "any user" or "any account". This allows the 
following valid combinations to be defined* 

U ser Acc o unt Meaning 

M N user M under account N 

M null user M under any account identifier 

nul I N any user under account N 

null null any user under any account identifier 

The (M,N) combination is, of course, most specific. The 
(null, null) combination defines a oublic file if any access 
rights are enabled or a private file if no access rights are 
enabled. Allowable access rights are* 

Exclusive - No other concurrent users are allowed 

Protected - Other concurrent readers are allowed 

Unprotected - Other concurrent readers and writers are allowed 

Input - Data may be retrieved from the file 

Output - The file may be written from its beginning 

Extend - Oata may be apDended to the file 

Update - Data may be retrieved/inserted/deleted/modified 

Execute - The Drogram in the file may be executed 

These rights sDecify only the type of access which the users 
identified by this entry are entitled to request when the file is 
attached or ooened. The users are not guaranteed they can 
actually exercise a right when they eventually 3sK to do so since 
another user may have a conflicting access right in effect at 
that time. For example, a file C3n not be attached for exclusive 
use if it is currently attached by another job, even though the 
user is entitled to exclusive access. 

An Access Control List is internally ordered 3nd processed 
in such a way that individual entries are checKed before group 
entries. Access rights are selected from the first entry which 
satisfies the user/account combination. 
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2.5 FILE SHARING 



A major design objective of the Data Management system is to 
provide adequate support for orocessing of shared files* 
Traditional support for shared read-only or read-execute files is 
rel ati vel y strai ght forward since the content of the file is not 
modified. The major design requirement is simply to permit 
multiple cooies of the necessary run-time control tables to be 
establ ished. 
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Sharing is suDoorted only for permanent mass storage files* 
At the time a permanent mass storage file is attached to a job, 
one of three sharing options and one of five usage options are 
specified. These selections identify the way in which the 
requesting job wishes to share and use the file* After the file 
is opened, explicitly selectable locking conventions are defined 
to permit data accesses to be coordinated. 

Sharing and usage ootions are defined in section Z. 1 * and in 
the relevant request descriptions. Appendix B summarizes the 
valid combinations of concurrent sharing and usage options* 
Locking conventions are defined in the sections on record 
management reauests and block management requests. An expanded 
definition of the three sharing ootions apoears below. 

Exclusive - Only one job may be attached* Only one 
concurrent open is permitted* Explicit lock selections 
are not required and are iqnored if issued. 

Protected - Multiple jobs may be^attached but no o ther Job 
can modify data in the file. Multiple concurrent opens 
are permitted, only one of which (in the current job, of 
course) may allow data modification* Explicit lock 
selections are not required and are ignored if issued* 
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2.0 3ASIC CONCEPTS 

2.6 FILE ACCESS PROCEDURES (FAPS) 



Unprotected - Multiple jobs may be attached and any job can 
modify data in the file. Multiple concurrent opens are 
permitted and any of them may allow data modification. 
Explicit lock selections are honored by the system and are 
mandatory if data is to be modified (records may not be 
replaced or deleted unless previously locKed). 
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2.6 FTLE ACCESS PROCEDURES (FAPS) 



File Access Procedures are procedures which may be inserted 
into the normal flow of control between the user and the data 
management system. FAPs may execute at either the user level or 
the subsystem level and tyDically will be employed to extend the 
apparent capability of tne data management system. 

When a file is defined, the owner of the file may select an 
associated FAP by specifying only its entry point (if at the user 
level) or an entry Doint within a specified subsystem that has 
been registered with IPLOS. Subsequent data management requests 
for that file will be routed*, by standard linking conventions, to 
the FAP. The FAP has complete freedom to choose whether to pass 
the request on to the data management system, to process the 
request ifsalf, or to issue additional requests in d I ace of the 
original request. Although the standard linkage conventions can 
be bypassed by 3 call issued directly from the user to the 
system, this condition is detected (if the FAP executes at the 
subsystem level) and the illegal call is rejected. 

Major anticipated uses for user-level FAPs include? 

a) urocessing non-IPL data formats on interchange media. 

b) generation of logging or audit trail files 

c) simulation of data files for checkout purposes 

Major anticipated uses for subsystem- 1 eve I FAPs include! 

a) orovision of the IPL Data Base Management facilities 

b) instal lat ion-supo 1 ied security procedures 

The data management system permits a single FAP to be 
defineo for a given file. If multiple non-standard functions are 
required to be apolied to the file (logging and code conversion, 
for example) then the multiple functions must be provided by a 
single FAP, 

NOTE: The user should be aware that a FAP, since it receives 
control between the user and the system, may choose to 
modify the user's initial description of a file. The 
File Control Block will then contain whatever the FAP 
wishes it to contain. 
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2.8 FIL£,0£,QANJ7AII0N 



The organization of a file defines its logical structure, is 
established when the file is first defined, and cannot 
subsequently be changed. With the exception of Library 

organization, a file organization is managed by standard 
Record-Level access procedures which are concerned with 
maintaining oroDer record relationships. At lower levels (block 
or segment level) a file looks like a string of bits and file 
oganization has little, if any, meaning. 
are currently defined: Sequential, 
Library. 



Four file organizations 
Relative? Indexed and 



Sequential file organization is supported on 
media and is one in which predecessor-su 
relationships are determined by the order in whic 
placed into the file. Each record, except t 
unique predecessor. Each record, except the last? 
successor. A sequentially organized file on mass 
updated in place (records may be replaced) if the 
length is not changed. If a sequentially organiz 
file contains Y~format records, records may also 
deleted even though the record remains physica 
continues to occupy space. 
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elafive file organization is supported only on mass storage 
s and consists of fixed-length entries (addressed by the 
Is 1, 2, ..., N) which contain Y-format records. When the 
is created, the entry size is selected to accomodate one 
at record of the maximum soecified size and cannot 
uently be changed. Variable length records up to the 
m specified size may be stored and retrieved. Records may 
ored and retrieved in any sequence. Attempts to directly 
ve (by ordinal or file address) records which have been 
d or have never been written are detected and an error code 
urned. Similarly, attempts to store new records into 
s which already contain records are detected and an error 
s returned. Sequential retrieval causes eupty entries to 
passed; records are returned in the order they exist In the 
Sequential storage of new records implicitly generates 
Is that increase by one on each request. 

Although the rules for storage and retrieval of records 
conform to COBOL rules for Relative files, arbitrary use 
of these rules may result in unusual performance 
characteristics. For example, initially writing only 
record ordinals 1 and 50000 is permitted. Similarly* 
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opening the file and performing two sequential retrieval 
requests will return only the two existing records. 
However, the elapsed time required to sequentially store 
and retrieve the record at ordinal 50000 is likely to be 
extremely large. In general, sparsely oopulated files wll 
not show rapid performance with sequential operations. 

Indexed file organization is supported only on mass storage 
devices and allows both sequential and random access to records. 
Records are uniquely identified by the content of a key field 
located at a fixed position in each record. Records may be 
randomly processed by specifying either the value of the key or 
the file address assigned to a record at the time it was stored. 
Records may also be sequent ia I I y processed in ascending order of 
key values. Support of alternate record keys is provided through 
the Multiple Index Processor which is described in a separate 
speci f icat ion. 

Library organization is supported only on mass storage 

devices and is intended to contain only IPL Load Modules. 

Neither Record-Level nor Slock-Level access is available. A file 

having Library oroanization is also the only type of file which 

can have the Execute attribute associated with it. Files having 

Library oroanization are initially written through the OBLIGE 

utility program and may subsequently be opened for segment-level 
access? usually for execution. 

NOTE! The current definition of Library organization is 
somewhat misleading* since it does not have the usual 
attributes of a file organization. The specification 
of I i brary organization for a file currently is used 
only as a logical switch to invoke special checking of 
the "execute" attribute and the ring assignments. 
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2.9 FI LE CA TALOGS 



A file catalog exists for each mass storage volume set and 
is constructed at the time the volume set is initially 
formatted. A catalog is implemented as a single file of indexed 
organization. Entries in a catalog are represented as variable 
length records with unique symbolic keys. The external 
identifier of a mass storage file (the key of the record which 
describes the file) is composed of three parts: owner identifier* 
file name and generation number. Any cataloged file at an IPL 
site is uniquely identified by the foui — part identifier! volume 
set identifier, owner identifier, file name, generation number. 
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4.1 FM#D£FINE_FILE 



^.0 FIL£_MANAG£M£NI_R£QU£aiS 



File Management requests assist a user in preparing files 
for processing and disposing of them after processing is 
completed. AM requests except those which open a file* close a 
file and close a tape volume are available both through Command 
Language and internally. These three are available only as 
internal requests. 

Before opening a file, an open descriptor must be allocated 
in any memory addressable by the user. The open request places 
in the open descriptor an internal file identifier and a link to 
the appropriate access procedure. The open descriptor is a 
required parameter on all explicit requests made while the file 
is open (open, close and close-volume File Management requests, 
all record-level and block-level requests). 

All other File Management requests have the identifier of 
the File Control Block (fcbid) as a required parameter. Through 
Command Language, this is the LNS name of the File Control 
Block. The form of fcbid for internal requests is currently 
being reassessed. Its precise form will ba defined in a 
subsequent update to the GDS and will either be identical to the 
external form (the LNS name of the File Control Block) or will be 
a pointer to an internal descriptor of the File Control Block. 

File Management requests execute serially with respect to 
the requestor. The request status field, which is set before 
returning from each reauest, specifies whether the request was 
completed successfully or was terminated because of an error 
condition. Error conditions are defined in Appendix E. 
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4.1 FH ftDEFINE FILE. 

This request constructs a File Control Block and places 
parameters into it or merges parameters into an existing File 
Control Block. If the File Control Block exists, the field 
values transmitted through this reauest will be olaced into the 
File Control Block only if the corresponding File Control Block 
fields contain a null value. The request and its oarameters aret 

FM#DEFINE_FILE (fcbname, paramblock, status) 

fcbname: the LNS name of the File Control Block that is to be 
constructed or modified (required). 

paramblock: the location of the parameter block which 
contains the field values for the File Control Block 
(required) . 



status: the location of the status 
(required) . 



field for this request 



This request is rejected if the File Control Block exists 
and is currently locked. The fields of the parameter block that 
may be transmitted to the File Control Block through this request 
are described in Aooendix A. The SHL reoresen t ati on of the 
parameter block is described in Appendix G. 
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<+.2 FM£CS£AIE_FILE 



This request creates a temoorary mass storage file. Null 
fields in the specified File Control Block are supplied default 
values at this time and the physical mass storage soace for the 
file is allocated . The request and its parameters ares 

FM#CR£ATE_FILE (fcbid, blocks, vord, rau, status) 

fcbid: the identifier of the File Control Block for this file 
(required) • 

blocks: the number of blocks to be allocated (optional). The 
size of each block is specified in the File Control 
Block. If this parameter is null, an 

installation-supplied default value is chosen. 

vord: the volume ordinal » within the volume set identified in 
the File Control Block, on which to restrict the space 
allocation (optional). 

rau: The relative allocation unit, within the volume 

identified by the vord parameter, at which to begin the 

allocation (optional and cannot be specified unless the 
vord parameter is also specified). 



status: the location 
(required ) • 



of the status field for this request 
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This request allocates additional space for a temoorary or 
permanent mass storage file. The request and its parameters are: 

FM#EXPAND__FILE (fcbid, blocks, vord, rau, status) 

fcbid: the identifier of the File Control Block for this file 
(required) • 

blocks: the number of additional blocks to be allocate 
(required). The size of each block is specified in the 

Fi Ie Contro I B I ock. 

vord: the volume ordinal, within the volume set identified in 
the File Control Block, on which to restrict the space 
allocation (optional). 

rau: the relative allocation unit, within the volume 
identified by the vord parameter, at which to begin the 
allocation (optional and cannot be specified unless the 
vord parameter is also specified). 



status: the location 
(required ) • 



of the status field for this request 



The use of the vord and rau Darameters is the same as 
described in the FMtfCPEA TE_FILE request. This request may only 
be issued by the owner of the file and only if the file is 
exclusively attached (if permanent) or created (if temporary) and 
is not currently ooen. Note that implicit expansion of the file 
will be done as needed by the system if the maximum file size and 
expansion increment are specified appropriately in the File 
Control Block. Explicit expansion is intended to accomodate the 
user who wishes to exercise more control over the physical 
placement of the file. 
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<♦•<<• FMflCONTRACT FILE 

This request releases mass storage space currently allocated 
to a temDorary or permanent file. The request and its parameters 
are: 

FM#CONTRACT_FILE (fcbid, Dlocks, status) 

fcbid: the identifier of the File Control Block for this file 
(required) 

blocks* -the number of blocks of current I y a 1 1 ocated space to 
be returned (optional). 

status: the location of the status field for this request 
(required ) • 

This request is valid only for mass storage files. It may 
be issued only by the owner of the file and only if the file is 
attached for exclusive use (if Dermanent) or created (if 
temporary) and is not currently open. 

If the value of the "blocks" parameter is null, unused space 
(beyond the highest recorded block number) is released. 
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^. 5 FMftSAVE FILE 



This request converts a temoorary mass storage file to a 
permanent file and records its logical and Dhysical description 
in the file catalog of the appropriate volume set. The ownership 
of the file is permanently established at this time. The request 
and its parameters are: 

FM#SAVE_FILE (fcbid, filename, generation, status) 

fcbid: the identifier of the File Control Block for this file 
(required ) • 

filename: the external name under which the file is to 

cataloged (optional). If filename is omitted, the system 

will attempt to catalog the file using the LNS name of the 
Fi le Control Block. 

generation: the generation number under which the file is to 
be cataloged (optional). If this parameter is omitted, a 
generation number of 0001, or a generation number one 
greater than the highest generation number existing for 
the specified name, will be assigned. 



status: the location of the status field 
(required) 



for this request. 



This request is valid only for temporary mass storage files 
and may be issued only if the file has been created and is not 
currently open. After successful completion of this request, the 
file attributes are identical to those of a permanent file which 
is attached for exclusive use. 
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<♦•& FM#D£LET E FI LE 



This request causes a temporary or permanent mass storage 

file to be deleted from the system and all of its allocated space 

to be returned for subsequent reuse*. The request and its 
parameters are* 

FM#DELETE_FILE ( f cb id , status) 

fcbid* the identifier of the File Control Block for this file 
(required) • 

status: the location of the status field for this request 
(required ) • 

This request may be issued only by the owner of a file and 
only if the file is attached for exclusive use (if permanent) or 
created (if temporary) and is not currently open. 
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FM#ATTACH_FILE (fcbidt use, status) 



fcbid: the identifier of the File Control Block for this file 
(required) • 

use* the sharing and use selection for this attachment of the 
file (optional). This parameter may have one of six 
val ues* 

E - Exclusive use 
PI - Protected input 
PU - Protected uodate 
PX - Protected execution 
UI - Unprotected input 
UU - Unprotected uDdate 



Omission 
se I ected. 



of this parameter causes exclusive use to be 



status* the location of the status field for this request 
(required) . 

Appendix B summarizes the open uses that may be selected for 
each attach use and also summarizes the valid concurrent attach 
uses. 

Three categories of information may be supplied in the File 
Control Block to conditionally override the corresponding 
cataloged values. 

it Buffering selections override the cataloged selections 
if no conflicts with current attach selections are 
detected. 
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<f.O FILE MANAGEMENT REQUESTS 
k.7 FM#ATTACH_FILE 



Access-level selection override 
if no conflicts with concurrent 
detected, except that record 
selected if block-level or s 
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<f.8 FMflDETA CH FI LE 



This request causes a permanent mass storage file to be 
detached from the current job. Intermediate operations performed 
include* decrementing internal usage counts associated with the 
file, releasing internal tables associated with the file if no 
other jobs are attached, updating usage statistics in the 
cataloged description of the file and unlocking the File Control 
Block associated with the file in this job. The request and its 
parameters ares 

FM#DETACH_FILE (fcbid, status) 

fcbidJ the identifier of the File Control Block for this file 
(required) • 

status? the location of the status field for this request 
(required ) • 

This request may be issued only if the file is currently 
attached to this job (either by explicitly attaching a permanent 
mass storage file or by creating a temporary mass storage file 
and then saving it) and is not currently open. 
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<+.0 FILE MANAGEMENT REQUESTS 
<+.9 FM#OPEN_FILE 



<♦. 9 FM£C1PEN_FILE 



This request establishes a logical connection between a file 
and an executing program and constructs the internal tables 
necessary to allow access to the data contained in the file. A 
file must be opened before any data transfer requests are 
allowea. The request and its parameters are! 



FM#QPEN_FILE 
status) 



(fcbid, opendesc, use? labelproc, segno, pva, 



fcbid: the identifier of the File Control Block for this file 
(required ) • 

opendesc: the address of an Open Descriptor which will be 
used to reference the file while it is ooen (required). 
Upon completion of the open request* the Open Descriptor 
contains two values which specify: (a) the internal 
identifier of the file (relevant only to the data 
management system), (b) a pointer to a binding section 
entry which identifies the procedure to call for all 
requests while the file is ooen. 

use: the use option selected for this instance of open of the 
file (required). This parameter may have one of file 
values: 

I - input 
- output 
E - extend 
U -• update 
X - execution 

labelproc: the entry ooint of a uset — supplied label 
processing routine which is exoected to be entered when 
labels are encountered (optional)* Omission of this 
parameter causes the system to follow standard label 
processing procedures. 

segno: the process segment number under which the file is to 
be ooened (optional and has meaning only for segment- I evel 
access). If specified, the segment number must have 
previously been reserved. If null, a segment number will 
be chosen and returned in the ova field. 

pva: the process virtual address to be used for segment level 
access (returned after successful completion of open for 
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segment- I evel access). 

status: the location of the status field for this request 
(required ) • 

Input usage means that the file exists and will be 
considered read-only while open. It is positioned at its 
beginning and only retrieval and positioning requests are 
allowed. Output usage means the file is being initially written 
or rewritten. It is positioned at its beginning and only data 
storage requests are al lowed. Extend usage means that data is 
being appended to the file. It is positioned at 
end-of -recorded-data and only data storage requests are allowed. 
Update usage means that all requests are valid, subject only to 
limitations imDosed by hardware or file organization. Execute 
usage, which may be selected only for Library file organzation, 
means that the program contained in the file will be executed. 

Appendix B summarizes the valid open usage selections for 
each attach usage selection. Temporary mass storage files and 
non mass storage files are treated as though they are attached 
for exclusive use. Ooen usage selections must be validated by 
Access Control List cnecKs (on files which have Access Control 
Lists) . 

Mass storage file may be opened after they have been created 
(if temporary) or attached (if permanent). 

Files on magnetic taoe may be opened after a File Control 
Block has been defined and Volume Sets have been attached to the 
job. Default values and/or values from standard labels are 
placed in the File Control Block at this time. Multiple 
instances of open of files on magnetic tape are not allowed* 

Files which mao to unit record devices may be opened after 
the device has been reserved and acquired and a File Control 
Block has been defined. Unit record device scheduling is 
described in the Job Management chapter of the GDS. 
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<f.Q FILE MANAGEMENT REQUESTS 
^ .11 FM#CLOSE_VOLUME 



k.10 FMflCLOSE FILE 



This request severs the logical connection between a file 
and an executing program that was established when the file was 
opened and Drevents access to the data contained in the file* 
The request and its parameters are: 

FM#CLOSE_FILE (ooendesc, disposition, status) 

ooendpsci the address of the oDen descriptor returned at the 
time the file was opened (required). 

disoosition: the disposition to be made of a taoe file after 
the close operation is completed (optional). This 

parameter may have one of the four values listed below: 

E - leave the volume oositioned at the end of the 

current file. 
8 - leave the volume positioned at the beginning of the 

current file. 

R - rewind the volume. 

U - rewind and unload the volume. 

Omission of this parameter causes the volume to be 
rewound. The parameter is ignored fop non-tape files. 

status? the location of the status field for this request 

(required) • 
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<+. 11 FM#C:LOS£_VOLLlMF 



This request causes the current volume of a tape file to be 
closed and a new volume opened. If the file is opened for output 
or extension then labels are generated, if necessary, and exits 
to usei — supplied label processing routines are taken. If the 

file is opened for input t then labels are checked and exits to 
user-supplied label processing routines are taken. The request 
and its parameters are: 

FM#CL0SE_V0LUME (ooendesc, disposition, status) 

opendesc: the address of the open descriptor returned at the 
time the file was opened (required). 

disposition: the disposition to be made of the current volume 
of tne file (optional). One of four values may be 
speci tied: 

E - leave the volume positioned at the end of the 

current file or file section. 
B - leave the volume positioned at the beginning of the 

current file or file section. 
R - rewind the volume. 
U - rewind and unload the volume. 



Omission 
rewound. 



of this oarameter causes the volume to be 



status: the location 
(required) 



of th-2 status field for this request. 
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4.0 FILE MANAGEMENT REQUESTS 
4.12 FM//PERMIT ACCESS 



ADVANCED SYSTEMS LABORATORY 
IPLOS GDS - DATA MANAGEMENT 



CHP0504 



4-16 
75/05/30 



4.0 FILE MANAGEMENT REQUESTS 
4.12 FM#PERMIT_ACCESS 



4. 12 F MflPE RM IT A CCE SS 



This request adds a new entry or modifies an existing entry 
in an Access Control List associated with a permanent mass 
storage file and describes the access rights which are to be 
allowed. The request and its parameters are! 



FM#PERMIT_ACCFSS (fcbid, 
useootion, status) 



useridi accountidt shareoption, 



fcbid: the identifier of the File Control 
(required ) • 



Block for this f i le 



userid: the identification of the user for which these access 
rights are being established (optional)* Omission of this 
parameter results in a null userid which is interpreted by 
the system as "any user". 

accountid: the identification of the account for which these 
access rights are being established (optional). Omission 
of this parameter results in a null accountid which is 
interpreted by the system as "any account". 

shareoption: the sharing options which are to be enabled for 
this combination of user and account for this file 
(required). This parameter may have any combination of 
the following three values: 

E - exclusive use is allowed 
P - protected use is allowed 
U - unprotected use is allowed 

useootion: the usage options which are to be enabled for this 
combination of user and account for this file (required). 
This parameter may have any combination of the following 
six values: 

I - the file may be attached and opened for input 

- the file may be attached and opened for output 

E - the file may be attached and opened for extension 

U - the file may be attached and opened for update 

X - the file may be attached and opened for execution 

status: the location of the status field for this request 
(required) • 

This request may be issued only by the owner of the file and 

NCR/CDC PRIVATE REV 5/29/75 
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on I y if the file 
current I y open. 



is attached for exclusive use and is not 



If this request results in creation of a new Access Control 
List entry then only the specified access rights are allowed. if 
an Access Control List entry already exists for this combination 
of user and account, then the specified access rights are "added 
to" the access rights currently defined. 
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4.0 FILE MANAGEMENT REQUESTS 
4.13 FM#PROHIBIT_ACCESS 
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4.0 FILE MANAGEMENT REQUESTS 
4.14 FM#REDEFINE_FILE 



^•13 FM#PROHIBIT ACCE SS 



This request adds 3 new entry or modifies an existing entry 
in an Access Control List associated with a permanent mass 
storage file and describes the access rights which are to be 
disallowed. The request and its parameters are: 



FM#PROHI3IT_ACCESS (fcbid* 
useoption, status) 



userid, accountid* shareoption? 



The parameter descriptions are identical to 
descriptions for the FM#PERMIT_ACCESS request. 



the parameter 



This request may be issued only by the owner of the file and 
only if the file is attached for exclusive use and is not 
currently open. 

If this reauest results in creation of a new Access Control 
List entry* then its effect is to deny access to the specified 
user and account combination. If an Access Control List entry 
already exists for this combination of user and account* then the 
specified access rights are "subtracted from" the access rights 
currently defined. 
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4.14 FM£tD£FIN£_FIL£ 



This request permits the owner of a mass storage file to 
redefine selected fields of the File Control Block. The request 
and its parameters are: 

FM#REDEFIN£_FILF (fcbid* paramblock, status) 

fcbid: the identifier of the File Control Block for this file 
(required). 

paramblock: the location of the parameter block which 
contains the new values for the fields which are to be 
redefined (required). 

status: the location of the status field for this request 
(required) • 

This request may be issued only by the owner of the file and 
only if the file is created (if temporary) or attached for 
exclusive use (if permanent) and is not currently open. 

The parameter block is constructed as described for the 
FM#DEFINE_FILE reauest. Alterable File Control Block fields are 
defined in Appendix A. Non-null values in the parameter block 
replace the value in the corresponding field of the File Control 
Block if the field is defined to be alterable. If the file is 
permanent* its cataloged description is uodated when the file is 
detached. 
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5.0 RECORD MANAGEMENT REQUESTS 

5.1 REQUEST BLOCK DESCRIPTION' 



5 . RECORD .MANAGEMENT. .REQUESTS 



Record-level access to files is provided through requests 
which perform six basic functions, record retrieval v record 
storage* record replacement* record deletion* record positioning 
and control selection. The reauests are functionally grouped as 
shown bel ow . 



Record Retriev 
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RM//REPLACED 
Record Deletio 

RM0DELETE 

RMtfDELETEK 

RMtfDELETEO 
Record Positio 

RMtfFINDF 
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RM//FINDK 

RM#FINDD 
Control Select 

RMtfLOCK 

RMtfUNLOCK 
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5.1 REQUEST BLOCK. DESCRIPTION 



Parameters to record-level requests are passed through a 
reauest block which is directly accessible by the user. Most 
requests also return status parameters in the request block that 
are in addition to the standard system request status. Fields of 
the request block are described below. 

opendesc - This field contains a pointer to the Open 
Descriptor that was initialized by the FM0OPENFILE 
request. 

bufadr - This field contains a pointer to the first byte of a 
record buffer which is located in memory that is directly 
accessible by the user. All record retrieval storage and 
replacement requests transfer data between the user's 
record buffer and internal* protected* block buffers. 
Direct access to the internal buffers is not allowed. 

buf length - This field contains the length* in bytes* of the 
record buffer. For retrieval requests* this field is 
typically set to the maximum record size defined for the 
file. For storage and replacement requests* this field 
specifies the amount of data to be transmitted. 

keyadr - This field contains a pointer to the record key and 
has meaning only for Indexed and Relative file 
organization. For Indexed files, the key consists of a 
byte string which identifies the record. For Relative 
files* the key is the ordinal of the record. 

keylength - This field contains the length* in bytes* of the 
record key and has meaning only for one request dealing 
with inoexed files. The RM#FINDK request permits 
positioning to be based on a selectable number of high 
order bytes of the key. All other keyed requests operate 
with the full key length defined for the file and ignore 
this parameter • 

fileadrin - This field contains the input fileaddress which 
is used by the four "direct" requests and the record 
locking requests to identify a record. 

compareopt - This field contains the comoare option to be 

used by the RM//FINDK request and may contain one of three 

values? =* >, >. Appropriate setting of this field 

permits a file ta be positioned to the first record whose 
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5.0 RECORD MANAGEMENT REQUESTS 

5.1 REQUEST BLOCK DESCRIPTION 
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5.0 RECORD MANAGEMENT REQUESTS 

5.1 REQUEST BLOCK DESCRIPTION 



key or ordinal is equal to, greater than* or greater/equal 
to the input key. 

lockopt - This field contains the record lock oDtion to be 
selected and may have one of three values! 
E - an exclusive lock is selected. Others may read the 

record. Only the selector of this lock may modify the 

record until the lock is cleared. 
S - a shared lock is selected. Others may read the 

record. No one, including the selector of this lock, 

may modify the record until the lock is cleared. 
Null - no lock is selected 

waitopt - This field contains the wait ootion to be selected 
if the selected lock ootion conflicts with a lock option 
that is currently in effect. The field may contain one of 
two values* 
R - reject the request if the specified lock option cannot 

immediately be satisfied, 
to* - wait until the specified lock option can be satisfied 

before returning from the request. 

delim - This field contains a user-specified one-byte data 
delimiter and has meaning only for files containing 
Y-format records. The contents of this field are copied 
into the corresponding field of the record header by each 
record storage request. The contents of the corresponding 
field of the record header are copied into this field by 
each record retrieval request. The field is intended to 
accomodate applications that require imbedded control 
information in a file and cannot use data records to 
describe the control information. 
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This field contains a one-bit binary flag and has 

only for files containing Y-format records. The 

of this field is copied into the corresponding 

of the record header, by each record storage 

The content of the corresponding field of the 

header is copied into this field by each record 

al request. The field is intended to accomodate 

tions (including Fortran formatted/unformatted I/O 

s) for which the concept of binary and coded 

has meaning. By convention, the value "zero" 

a coded record. The value "one" implies a binary 
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procedures. The fields are merely copied between 
the request block and the header of Y-format 
records. The contents of the fields may be 
interpreted or ignored by the user program. 

fileadrout - This field contains the file address of the 
record referenced by the most recent record-level access 
request and is set upon return from each request. 

count - This fiehd contains the transfer count associated 
with the preceding record storage, retrieval, or 
replacement request. It is an output parameter and 
defines the number of bytes transmitted to the user's 
buffer (by retrieval requests) or to the file (by storage 
and replacement requests). 

recordflag - This field specifies whether the preceding 
retrieval request transmitted- a complete or partial 
record. It is an output parameter and is set to zero to 
indicate that a complete record was transferred. The 
value "one" means that the preceding retrieval request 
transferred a partial record. 
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5.0 RECORD MANAGEMENT REQUESTS 

5.1 REQUEST BLOCK DESCRIPTION 
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5.0 RECORD MANAGEMENT REQUESTS 
5.2 PROCESSING SHARED FILES 



Appendix C summarizes the record-level access requests* the 
record-level request parameters* the parameters which have 
meaning for each request* and the requests which have meaning for 
each file organization and hardware type. 

The reauest descriptions in the following sections identify 
the oarameters that are applicable to each request but do not 
repeat the parameter descriptions appearing in this section. Two 
parameters which have not previously been described also appear 
in each request? 

rbss This oarameter is a pointer to the request block and 
conforms to standard IPLOS conventions for Task Services 
requests. 

status? This parameter is a pointer to the status area for 
the request and also conforms to standard IPLOS 
conventions for Task Services requests. 

All other applicable parameters are contained in the request 
block identified by "rba". 

Record management requests execute serially with respect to 
the requestor. The request status field* which is set before 
returning from each request* specifies whether the request was 
completed successfully or was terminated because of an error 
condition. Error conditions are defined in Appendix E. 
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5 . 2 PROCESSING SHARED FILES 



When a permanent mass storage file is simultaneously open 
more than once, and any form of data modification is allowed, 
facilities are provided to assist in coordination of Drocessing 
through the multiple instances of open. 

Proper selection of the 1 ockoot and waitoot oarameters on 
record storage and retrieval requests and/or proper use of the 
RMtfLOCK and RM#UNLOCK requests oermit updates to a record or set 
of records to be controlled and properly sequenced. 

The tyne of lock to be placed on a record is specified by 
the lockoot parameter. A shared lock allows the record to be 
retrieved through any instance of ooen but prevents the record 
from being modified. An exclusive lock allows the record to be 
retrieved through any instance of ooen and also allows it to be 
modified through the current instance of open. 

The waitopt parameter specifies the type of action to be 
taken if a specified lock option conflicts with a lock option 
currently in effect through another instance of ooen (a conflict 
is an attemot to set an exclusive lock if any lock is currently 
in effect or an attempt to set a shared lock if an exclusive lock 
is in effect). If the wait option is R» the request is rejected 
if the specified lock option cannot be selected. I'f the wait 
ootion is W, the request is queued and the requestor will wait 
until the specified lock option can be selected unless, queueing 
the request would generate a deadlock condition. 

A deadlock condition exists if the program which has the 
specitied record currently locked it also queued waiting 
(directly or indirectly) for another record that is currently 
locked through this instance of open. The action taken when a 
deadlock is detected is to reject the request. A user should* 
therefore, lock all records of a set which require "simultaneous" 
update before performing any of the updates. A user should also 
be prepared to unlock all records in the set and reinitiate the 
entire locking seouence in case a deadlock is detected by the 
system. 



The valid comb ina't ions of current 
existing lock selections are shown below: 



lock selection 



and 
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5.0 RECORD MANAGEMENT REQUESTS 
5.2 PROCESSING SHARED FILES 
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5.0 RECORD MANAGEMENT REQUESTS 
5.3 RMtfGET 
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5.3 £MJM££I 



This request transfers the "next" existing record or partial 
record from a file to a buffer. The request and its input 

parameters are: 

RM//GET (rba, status* opendesc» bufadr, buflength, lockopt* 
waitoot) 

Output parameters are: 

(delim, binflaq* fileadrout, count, recordflag) 

The request has meaning tor all file organizations and all 
hardware types for which data retrieval is defined. Successive 
RM//GET requests retrieve 1 records in an order determined by the 
organization of the file. Records in sequentially organized 
files are retrieved in order of their physical placement. 
Records in files having Indexed organization are retrieved in 
order of ascending value of the record key. Records in files 
having Relative organization are retrieved in order of ascending 
value of record ordinal (empty entries are skipped). 



All transfers begin at a record boundary and are 
by the smaller of record length or buffer length. 



terminated 
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5.0 RECORD MANAGEMENT REQUESTS 
5.<t RMtfGETP 



5. k RM£££IP 

The request transfers the remainder or partial remainder of 
a record from a file to a buffer. The request and its input 
parameters arei 

RMtfGETP (rba, status* opendesc, bufadr, but length) 

OutDUt parameters arei 

(count* record flag) 

The request is valid only for sequentially organized files 
and is intended to continue the retrieval of a record which was 
partially retrieved by a orevious request. Transfers begin at 
the location, within the record, following the end of the 
preceding partial transfer and are terminated by the smaller of 
remaining record length or buffer length. The request is not 
valid unless the preceding request caused the partial record flag 
to be set . 

NOTES RMtfGETP cannot begin a transfer at a record boundary 
and cannot cross a record boundary. It can only be 
used to comolete the transfer of a ~ecord that was 
started with one of the other retrieval requests. 
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5.0 RECORD MANAGEMENT REQUESTS 
5.5 RMtfGETK 



5.5 RM1GJEIK 



This request transfers a record, identified by its key value 
or ordinal value, from a file to a buffer. The request and its 
input parameters arei 

RMtfGETK (rba, status, opendesc, bufadr, but length, Keyadr, 
I ocKopt , waitopt ) 

Outout Darameters areJ 

(delim, binflaq, fileadrout, count, recordflag) 

The request is valid only for files havinq Indexed or 
Relative organization. For Indexed organization, the keyadr 
parameter points to the first byte of the symbolic key of the 
record to be retrieved. For Relative organization, the keyadr 
parameter points to the ordinal of the record to be retrieved. 
All transfers begin at a record boundary and are terminated by 
the smaller of buffer length or record length. 

The request is rejected if a record with the specified key 
does not exist in the file. 
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5.0 RECORD MANAGEMENT REQUESTS 
5.6 RM#GETD 
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5.0 RECORD MANAGEMENT REQUESTS 
5.7 9M#PUT 



5.6 RMflGETD 



This request transfers a record* identified by its file 
address, from a file to a buffer. The request and its input 
parameters are: 

RMtfGETD { rba * status* opendesc* bufadr, but length* fileadrin, 
lockopt, waitopt) 

Output parameters are: 

(delim» binflag, fileadrout* count* recordflag) 

The request is valid only for mass storage files. All 
transfers begin at a record boundary and are terminated by the 
smaller of buffer length or record length. The input file 
address will typically have been saved from the time the record 
was stored in the file. 

The request is rejected if the specified record does not 
exist in the file. 
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5.7 RM0PUT 



This request transfers a record* or completes the transfer 
of a record, from a buffer to the "next" location in a file. The 
request and its inout parameters are: 

RM#PUT (rba, status, opendesc, bufadr, buflength* lockopt* 
de I im* binf lag ) 

Output parameters are 

(fileadrout, count) 

It the file contains fixed length records* the record is 
blank filled to the correct length if necessary and the count 
parameter shows the actual length transferred to the file. If 
the file has Indexed organization, the Key of the record must be 
greater than the key of the preceding record. If the file has 
Relative organization* an ordinal one greater than the ordinal of 
the preceding record is assigned. 

This request unconditionally marks the end of recorded data 
on the file. Records may not be retrieved beyond this point. 
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5.0 RECORD MANAGEMENT REQUESTS 
5,3 RM#PUTP 
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5,0 PFCORD MANAGEMENT RFQUESTS 
5.9 KMtfPUTK 



5. 8 £M£PUI£ 



This request transfers a partial record from a buffer to a 
file. The request and its input parameters are: 

RM#PUTP (rba* status, opendesc* bufadr, buf length, delim, 
binf laq) 

Outout parameters are! 

(fileadrout, count) 

The request is valid only for sequentially organized files 
and either begins or continues the storaqe of a new record. If a 
new record is being started (the preceding request was not 
■RM#PUTP) the delim and binf lag parameters have meaning. If a new 
record is being continued (the preceding request was RM#PUTP) the 
delim and binflag parameters are ignored. 

The partial record requests are intended to accomodate 
applications which are unable to transfer complete records, 
usually because the records Br e extremely long. These records 
can be written by use of a sequence of RM#P0TP requests followed 
by RMtfPUT to terminate the record. The records can subsequently 
be read by RM#GET or RMtfGETD f o I I owed by a sequence of RM#GETP 
requests (if necessary) to complete the retrieval. 
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5.9 RM£PUJK 



This request transfers a record, identified by its key value 
or ordinal value, from a buffer to a file. The request and its 
input parameters are! 

RMtfPUTK (rba, status, ooendesc, bufadr, buf length, keyadr, 
lockopt, delim, binflag) 

Output parameters are! 

( f i ledrout, count) 

The request is valid only for files having Indexed or 
Relative organization. For indexed organization, the key value 
is obtained directly from the record buffer and the keyadr 
parameter is ignored. For relative organization, the keyadr 
Darameter points to the ordinal of the record to be stored. 

The request is rejected if a record with an identical key 
already exists in the file. 
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5.0 RECORD MANAGEMENT REQUESTS 
5.10 RM#REPLACE 
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5.0 RECORD MANAGEMENT REQUESTS 
5.11 RMtfREPLACEK 



5.10 RMtfREPLACE 

This request replaces the record obtained through an 
immediately Dreceding retrieval request. The request and its 
input parameters are: 

RMtfREPLACE (rba, status, opendesc, bufadr, but length) 

Output parameters are* 

( f 1 leadr.outf count) 

The request is valid only for mass storage files. For 
Sequential organization, the length of the record cannot be 
changed and the file cannot contain spanned records (of either S 
or Y format). For Indexed organization, the value of the key may 
not be changed. The reauest is rejected if it is preceded by any 
request other than RMtfGET, RM#GETK or RM#GETD. 
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5.11 SHIR £EL ACE£ 

This request replaces a record, identified by its Key value 
or ordinal value, in a file. The request and its input 
parameters are: 

FMRFPKEY (rba, status* ooendesc, bufadr, buflength, keyadr) 

Output parameters are 

(fileadrout, count) 

The request is valid only for files with Indexed or Relative 
organization. For Indexed organization, the key value is 
obtained directly from the record buffer and the keyadr parameter 
is ignored. For Relative organization, the keyadr parameter 
points to the ordinal of the record to be replaced. 

The request is rejected if a record with the specified key 
does not exist in the file. 
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5.0 RECORD MANAGEMENT REQUESTS 
5.12 RMflREPLACED 



This request replaces a record, identified by its file 
address, in a file. The request and its inout parameters areX 

RMtfREPLACED (rba, status, opendesc, bufadr, buflength, 
fileadrin) 

Output parameters are J 

(fileadrout, count) 

The request is valid only for mass storage files. For 
Sequential file organization, the length of the record cannot be 
changed and the file cannot contain spanned records (either S or 
Y format). For Indexed organization, the value of the key may 
not be changed. 

The request is rejected if tne specified record does not 
exist in the f i le. 
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5.0 RECORD MANAGEMENT REQUESTS 
5.13 RM// DELETE 



5.13 £M£OEL£IE 



This 



request deletes the record obtained through an 
immediately preceding retrieval request. The request and its 
input parameters are: 

RMflDELETE (rba, status, ooendesc) 

The output parameter is x 

(f i leadrout) 
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5.0 RECORD MANAGEMENT REQUESTS 
5.14 RM#DELETEK 



5.14 RMtfOELETEK 

This request deletes a record* identified by its Key value 
or ordinal value? from a file. The request and its input 
Darameters aret 

RMtfDELETEK (rba, status* opendesCf Keyadr) 

The output parameter is* 

(f i leadrout ) 

The request is valid only for files with Indexed or Relative 
organization and is rejected if the specified record does not 
exist in the file. 
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5.0 RECORD MANAGEMENT REQUESTS 
5.15 RMtfDELETED 



5.15 RMtfOELETED 

This request deletes a record, identified by its file 
address, from a file. The request and its input Darameters are* 

RM#DELETED (rba, status, opendesc, fileadrin) 

The output parameter is: 

(f i leadrout ) 

The request is valid only for mass storage files and is not 
valid for sequentially organized files unless they contain 
Y-format records. The request is rejected if the specified 
record does not exist in the file. 
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5.0 RECORD MANAGEMENT REQUESTS 
5.16 RM#FINDF 



5.16 ^MflFINDF 

This request oositions a file to the first data record. The 
request and its inDut parameters are: 

RM#FINOF (rba, status, opendesc) 

The output parameter is: 

(fileadrout) 

The request is valid for all file organizations and all 
hardware types for which positioning is defined. 
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5.0 RECORD MANAGEMENT REQUESTS 
5.17 RMtfFINDP 



5,17 RMffFINDP 

The request positions a file to the "preceding" record. The 
raquest and its input parameters are! 

RMtfFINDP (rba, status, opendesc) 

The output parameter is: 

(f i leadrout) 

The request is valid only for sequentially organized files 
and hardware tyoes for which Dositioning is defined. The request 
exists solely to satisfy a Fortran reauirement and reasonable 
performance should not be expected unless the file contains 
format F or U records. 
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5.0 RECORD MANAGEMENT REQUESTS 
5.18 RM#FINDK 
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5.0 RFCORD MANAGEMENT REQUESTS 
5.19 RM#FINOD 



5. 13 RM£FINJDK 



This request oositions a file to a record whose Key value or 
ordinal value satisfies a specified search criterion. The 
request and its inDut parameters are: 



RMflFINDK (rba, 
compareopt ) 



status* 
The output parameter isl 



opendesc, keyadr, keylength* 



(f i leadrout) 
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the first record whose key value is greater 
ut key value. 

the first record whose key value is greater 
I to the input key value. 



The request is rejected if no record satisfying the 
specified search criterion can be found. 
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5.19 R MffFI NPD 

This request oositions a file to a record identified by its 
file address. The request and its input parameters are! 

RM#FINDD (roa, status, fileadrin) 

The output parameter is: 

(f i leadrout) 

The request is valid only for mass storage files and is 
rejected if the specified record does not exist in the file. 
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5,0 RECORD MANAGEMENT REQUESTS 
5.20 KM#LOCK 



5.2 RJJIU&K 



This request sets a shared or. exclusive lock on a specified 
record. The request and its input parameters ares 

RM#LOCK (rba, status? ooendesc, fileadrin, lockopt, waitopt) 

No output parameters are defined. 

The request is valid onlv for mass storage files and is 
intended to permit concurrent users of the file to coordinate 
their accesses to data. The effect of this request is to place a 
lock on a record (identified by the fileadrin parameter) through 
an instance of open (identified by the opendesc parameter). 
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5.0 RECORD MANAGEMENT REQUESTS 
5.21 RIWUNLOCK 



5.21 RM/HJNLOCK 

This request clears a lock on a record that was previously 
set through this instance of open. The request and its 
parameters are? 

RMtfUNLOCK (rba, status, ooendesc, fileadrin) 

No output parameters are defined. 

The request is a companion to the PMtfLOCK request. If the 
fileadrin parameter is not null, the lock is cleared on the 
specified record. If the fileadrin parameter is null, the locks 
are cleared on all records currently locked through this instance 
of open. 
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6.0 BLOCK MANAGEMENT REQUESTS 

6.1 REQUEST BLOCK DESCRIPTION 



6.0 



U REQUESTS 



Block- level access to files- is provided through requests 
which perform four basic functions! block retrieval* block 
storage* block positioning and control selection. The requests 
are functionally grouped as shown be low J 



Block Retrieval Re 

8M#READ 

BM0READO 
Block Storage Requ 

BM#WRITE 

BM#WRITED 
Block Positioning 

8M0POINTF 

BM0POINTL 

BM0POINTP 
Control Selection 

BMSREADSTATUS 

BM#SELECT 

BM#CANCEL 

BM0LOCK 

BM#UNL0CK 



quests 

(retrieve next block) 

(retrieve block* direct) 

ests 

(store next block) 

(store block, direct) 

Requests 

(position to first block) 

(position to last olock) 

(position to preceding block) 

Requests 

(retrieve extended status) 

(transmit device-dependent function) 

(cancel outstanding request) 

(set a block lock) 

(clear block lock(s)) 
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6.1 REQUEST BLOCK DESCRIPTION 



Parameters to Dlock-level requests are passed through a 
request block which is directly accessible by the user. Most 
requests also return status parameters in the request block that 
are in addition to the standard system request status. Fields of 
the request block are descriDad belowl 

opendesc - This field contains a pointer to the Open 
Descriptor that was intialized by the FM#OPEN_FILE 

request. 

ecbptr - This field contains a pointer to the Event Control 
Block associated with this request. Use of the Event 
Control Block Tor monitoring the progress of asynchronous 
requests is discussed in section 6.2. 

bufadr - This field contains a pointer to the first byte of a 
block buffer which is located in memory that is directly 
accessible by the requestor. 

buflength - This field contains the length, in bytes, of the 
block buffer. For retrieval requests, this fie t ld is' 
typically set to the maximum block size defined for the 
file. For storage requests, this field specifies the 
amount of data to be transmitted. 

blocknum - This field contains the block number at which a 
direct transfer is to begin. It has meaning only for 
mass storage files and is interpreted as a re I ative ,b lock 
number within the file. The first block of a file is 
numbered one. . 

function -. This field contains a device-dependent function 
and has meaning only for the BMtfSELECT request. 

lockopt - This field contains the olock I oc* option to be 
selected and has meaning only for the BM#L0CK request. 
One of two values may be specified* 

E - an exclusive lock is selected. Others may read 
the block. Only the selector of this lock may 
write the block until the lock is cleared. 
S - a shared lock is selected. Others may rea'd the 
block. No one, including the selector of this 
lock, may write the block until the lock is 
cleared. 
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waitopt - This fie Id contains the wait option to be selected 
if the specified lock option conflicts with a lock option 
that is currently in effect. One of two values may be 
specif ied : 

R - reject the request if the specified lock option 

cannot immediately be satisfied. 
W - wait until the specified lock option can be 
satisfied before returning from the request. 

count - This field contains the transfer count associated 
with the request. It is an output parameter and defines 
the number of bytes transmitted to the buffer or to the 
file. The field is cleared when the request is issued 
and is set when the request is completed. 

response - This field contains a summary of responses 
received since the request associated with this request 
block was issued. The field is cleared when the request 
is issued and is updated as responses are received. 
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ApDendix D summarizes the block-level requests* the 
blocK- level request parameters? the parameters which have meaning 
for each request* and the requests which have meaning for each 
open usage and hardware type. 

The request descriptions in the following sections identify 
the parameters that are aDplicable to each request but do not 
repeat the parameter descriptions aopearing in tnis section. Two 
parameters which have not been oreviously described also appear 
in each request. 

rba - This parameter is a pointer to the request block and 
conforms to standard IPLOS conventions for Task Services 
requests. 

status - Ths parameter is a pointer to the status area for 
the request and also conforms to standard IPLOS 
conventions for Task Services requests. 

All other applicable parameters are contained in the request 
block identified by "rba". 
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6.2 



MONITORING 



BlocK Management requests may be executed synchronously with 
the requestor (the request is completed before control Is 
returned) or asynchronously with the requestor (control is 
returned before the request is completed). 

The status of a synchronous request is available in the 
status field identified for the request. The status field also 
specifies whether the request has either been completed normally 
or has been rejected because of an abnormal condition. In the 
latter caset the reason for rejecting the request is also 
specif ied. 

Asynchronous requests are executed in parallel with the 
requestor. At the time control is returned* the request status 
field specifies whether the request was accepted and initiated or 
was rejecfed. The status of the operation described by the 
request is automatically returned by the system in the "response" 
field of' the original request b I ocK after the asynchronous 
operation is complete. 

A requestor may use the Program Management event monitoring 
requests listed below to keep informed of the progress of an 
asynchronous requests 

PM#ATTACH_PROCEDURE 

PM0DETACH.PROCEDURE 

PM0ENABLE.EVENT 

PM#DISABLE_EVENT 

PM#SIATUS_£VENT 

PM#WAIT_EVENT 

PM#WAIT_CLEAR_EVENT 

PM#CLEAR_EVENT 

By defining an Event Control Block and placing its address 
in the Block Management request block* the requestor* in' effect* 
associates an event with a response from the asynchronous 
reauest. If the ecbptr parameter is not null* Block Management 
procedures "cause" the event when responses are received. I f an 
interrupt procedure is attached to the event* it is executed at 
the time the response is received (unless* of course* the 
requestor has disabled the event or in some other way* deferred 
its execut ion) . 

NOTE* A Block Management request block serves both as a 
parameter area for requests to the system and as a 

NCR/CDC PRIVATE REV 05/29/75 
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status area for responses from the system. 

Tnerefore* it is "active" for the life of the 

request and must not be reused until a final 
response is received. 
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6.3 RESPOND FQRttAI 



Altnough the exact response format cannot be specified until 
considerably more design work has occurred* the intent and 
partial content of responses are discussed in the following 
paragraphs! 
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3. 



the count field of the request block may be incremented 
more than once during the life of a requests 

the response field represents the logical sum of all 
intermediate responses that have occurred since the 
request was issued. 

the associated event is "caused" each time a response is 
received at the job level (this is not necessarily every 
time a response is received from the peripheral 
system) • 
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The exact format of the resDonse field is not. yet defined 
but is intended to include boolean values grouped into categories 
as shown below. The categories and examples under each category 
will be updated as more information is known. 

fianera, ! Status. 

o a final response (has) (has not) been received 

o intermediate responses (have) (have not) been received 

o error recovery (has) (has not) been attempted 

o the request was (successful) (abnormally terminated) 

Int ermed ia te Re sp onse T ype 
(t o be defined) 

A b n or faal^l^rmjiia. t jo n, T^g§ 

o unrecoverable transfer errors 

o read error 

o write error 

o lost data 
o inoperable hardware errors 

o device not ready 

o device busy ■ 

o address error 
o temporary error conditions 

o device temporarily reserved 

o a previous abnormal termination affects this request 

AliSDlion_Q a nj3iHons 

o partial block transfer occurred 
o multiple block transfer occurred 
o end of recorded data encountered 
o end of physical medium encountered 

B&Mie.gzP.s,Eten4ent.. Sialics 
(t o be def ined) 
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2-EI1ES 



When a permanent mass storage file Is simultaneously open 
more than oncet and any form of data modification is allowed* 
facilities are provided to assist In coordination of processing 
through the multiple instances of open. 

Proper selection of the. lockopt and waitopt parameters and 
proper use of the BM#L0CK and BMtfUNLOCK requests permit updates 
to a block or a set of blocks to be properly sequenced. 

The type of lock to be placed on a block is specified by the 
lockoot parameter. A shared lock allows the block to be 
retrieved through any instance of open but prevents the block 
from being modified. An exclusive lock allows the block to be 
retrieved through any instance of open and also allows it to be 
modified through the current instance of open. 

The waitopt parameter specifies the type of action to be 
taken if a specified lock option conflicts with a lock option 
currently in effect through another instance of open (lock 
conflicts are described in section 5.2). If the wait option is 
R, the BMtfLOCK request is rejected if the specified lock option 
cannot be selected. If the wait option is W, the request is 
queued and the requestor will wait until the specified lock 
option can be satisfied un less queueing the request would 
generate a deadlock condition. 

A deadlock condition exists if the program which has the 
specified block currently locked is also queued waiting (directly 
or indirectly) for another block that is currently locked through 
this instance of open. The action taken when a deadlock is 
detected is to reject the request. The requestor should* 
therefore* lock all blocks of a set which require '•simultaneous" 
update before retrieving the blocks and performing the updates. 
The requestor should also be prepared to unlock all blocks in the 
set and reinitiate the entire locking sequence in case a deadlock 
is detected by the system. 
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requests to perform these operations are made through the 
standard block management interface to the appropriate "file". 
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Similarly* diagnostic and maintenance subsystems could be 
implemented as protected subsystems which communicate directly 
with components of the peripheral systems through standard block 
management requests to special "files". Obviously* the "files" 
should either be partitioned from those in use for normal 
operation or great care should be taken to avoid disruption to 
concurrent users. The mechanisms for removing and returning 
these "files" from/to normal use are expected to be defined as 
the designs of both the operating system and the maintenance 
subsystem continue to be developed. 
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6.6 BMffk^An 



This request transfers data from the next block of a file to 
a buffer. The request and its parameters are: 

BMtfREAD (rba* status* opendesc* ecbptr* bufadr, buflengtht 
countf response) 

If the buffer length is less than the length of the block* 
excess data in tha block is not transferred. The resoonse field 
is set to indicate that a partial block transfer ocurred and the 
count field is set to the actual transfer size (the buffer length 
if the request completed normally). 

If the buffer length is greater than the length of the 
block, the action taken is hardware-dependent. 

1) For mass storage files, data is transferred from 
consecutive blocks until the buffe~ is filled to 
capacity. The response field is set to indicate that 
multiple blocks were transferred and the count field is 
set to the actual transfer size. 

2) For non-mass storage files, only a single block is 
transferred. The response field is set to indicate this 
fact and the count field is set to the actual transfer 
size. 
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6.0 BLOCK MANAGEMENT REQUESTS 
6.7 BM#READD 



6.7 £H#R£AnH 

This request transfers data from a specific block of a mass 
storage file to a buffer. The request and its parameters aret 

BMffREADD (rba, status* opendesc, ecbptr, bufadr, buf length, 
blocknum, count, response) 

The request is valid only for mass storage files. The rules 
for partial and multiple block transfers are identical to those 
described for the BM#READ request. 



1 
2 
3 

<♦ 

5 

6 

7 

8 

9 

10 

11 

12 

13 

1^ 

15 

16 

17 

18 

19 

20 

21 

22 

23 

2^ 

25 

26 

27 

28 

29 

30 

31 

32 

33 

3** 

35 

36 

37 

38 

39 

**0 

*»1 

kZ 

<*3 

<♦<♦ 

*»5 

<*6 

<*7 

<f8 



6.0 BLOCK MANAGEMENT REQUESTS 
6.8 8M0WRITE 



6.8 &M£M&II£ 



This request transfers data from a buffer to the next block 
of a file. The request and its parameters are* 

BM//HRITE (rba, status* opendesc, ecbptr, bufadr, buf length, 
count, response) 

The buffer length specifies the amount of data to be 
transferred and has hardware-dependent implications if it exceeds 
the maximum block length specified for the file. 

1) For mass storage files, data is transferred from the 
buffer to consecutive blocks in the file until the buffer 
is emptied. The response field is set to show that 
multiple blocks were transferred and the count field is 
set to the actual transfer size. 

2) For non-mass storage files, the request is rejected and 
the request status field is set to indicate the reason. 

If the buffer length is less than or equal to the maximum 
block length specified for the file, then only a single bloxk is' 
transferred for files on all hardware types. 

The BMtfWRITE request unconditionally marks the end of 
recorded data on the file. Data may not be retrieved beyond this 
point. 
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6.0 BLOCK MANAGEMENT REQUESTS 
6.10 BMtfPOINTF 



6.9 EMiHSIIEQ 

This request transfers data from a buffer to a specific 
block of a mass storage file. The request and its parameters 
areJ 

BM#WRITED Croat status* opendesc* ecbptr, bufadr, buf length, 
blocknum, count, response) 

The request is valid only for mass storage files, The rules 
for single and multiple block transfers are identical to those 
described for the BM#WRITE request. 

The 8M0WRITED request marks the end of recorded data on the 
file only if the transfer terminates beyond the existing end of 
recorded data. 
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6.10 B M0POINTF 



This request positions a file to the first data block. The 
request and its parameters are J 

BM0POINTF (rba, status, ooendesc, ecbptr, response) 

The request is valid for all hardware types for which 
positioning is defined. After successful completion of this 
request, the file, is positioned so that a BM#READ request will 
retrieve the first data block. For multivolume tape files, the 
file is positioned to read the first data block of the current 
file section • 

If the file is on mass storage, this request results only in 
the updating of an internal table. If the file is on magnetic 
tape, this request results in positioning of the physical 

medium. 



NCR/CDC PRIVATE REV 05/29/75 



NCR/COC PRIVATE REV 05/29/75 



AOVANCEO SYSTEMS LABORATORY 
IPLOS GOS - DATA MANAGEMENT 



CHP0504 



6-17 
75/06/11 



6.0 BLOCK MANAGEMENT REQUESTS 
6,11 BM0POINTL 
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6.0 BLOCK MANAGEMENT REQUESTS 
6.12 BMtfPOINTP 



6.11 QMffPOINTL 



This request positions a file to the last data block. The 
request and its parameters are* 

BM#POINTL(rba* status* opendesc* ecbptr* response) 

This request is valid for all hardware types for which 
positioning is defined. After successful completion of the 
request* the file is positoned so that a BM#READ request will 
return "end of recorded data" status. A BMfWRITE request will 
extend the file. For multivolume tape files? the file is 
positioned to the end of the current file section. 

If the file is on mass storage* this request results only in 
the updating of an internal taole. If the file is on magnetic 
tape* this request results in positionig of the physical medium. 
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6.12 BMlElilNIP 



This request positions a file to the 
block. The request and its parameters are: 



•preceding" data 



BM#POINTP (rba, status* opendesc* ecbptr* response) 

This request is valid for all hardware types for which 
positioning Is defined. After successful completion of this 
request* the file is positioned in front of the l3st data block 
accessed by the last preceding storage* retrieval or positioning 
request. 

If the file is on mass storage* this request results only in 
the updating of an internal table. If the file is on magnetic 
tape* this request results in the tape being backspaced one 
physical record. Multivolume tape files cannot be- backspaced out 
of the current file section. 
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6.0 BLOCK MANAGEMENT REQUESTS 
6.13 BMOREADSTATUS 
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6.0 dLOCK MANAGEMENT REQUESTS 
6.1<t BM0SELECT 



6.13 aMSEAgsTATllS. 

This request retrieves a variable amount of device-dependent 
status from the controller associated with the device on which 
the specified file resides. The request and its parameters are t 



BMffREAOSTATUS (rba, status* 
buflengtht count, response) 



opendesc, 



ecbptr , 



buf adr, 



This request is intended for use by diagnostic procedures* 
error recovery procedures* logging procedures or others which 
reauired device-dependent interaction with the peripheral 
system. 

The size limitations and data format of the buffer are 
device-dependent and will be defined as the appropriate 
controller specifications are developed. 
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6.1<* BM1SLLEUI 



This request transmits device-dependent functional data to 
the controller associated with the device on which the specified 
file resides. The request and its parameters are* 



BMtfSELECT (rba, status, opendesc, ecbptr, bufadr, 
blocKnum, function, count, response) 



buf I ength, 



This request is intended for use by diagnostic procedures, 
error recovery procedures, logging procedures or others which 
require device-dependent interaction with the peripheral system. 

The size limitations and data format of the buffer, the use 
of the blocKnum parameter and the meanings of the function 
parameter are device-dependent and will be defined as IPL 
peripheral specifications become available. 

NOTE* A cursory examination of a few existing controller 
specifications produced a list of over fifty functions 
that various controllers can recognize. Some 
functions can legitimately be made available to user 
programs that have non-shareao le files (such as t tapes)\ 
open for block-level access. Other functions can be 
made available only to authorized privileged system 
programs since. their misuse could lay waste to the 
system. As IPL peripheral specifications become 

avilable and their capabilities become Known, the 
availability of device-dependent functions to various 
types of procedures will be clarified. 
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6.0 BLOCK MANAGEMENT REQUESTS 
6.15 BMSCANCEL 



6.15 BMflC 



This request cancels a previously issued, asynchronous, 
block-level request. The request and its parameters are: 

BM#CANCEL (rba, status) 



The 
request t 
to a I I ow 
astray* p 
excessive 
another 
is misb 
clarif ica 
re lated s 



request block address identifies the previously issued 
hat is to be cancelled. The intent of this request is 

programs to terminate requests that appear to have gone 
ossibly because a reponse has .not been received for an 
ly long time or because an abnormal response from 
equest indicates that something in the peripheral system 
ehaving. The limitations of this request and 
tion of other uses will be defined as the design of all 
ystem components becomes better known. 
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6.0 BLOCK MANAGEMENT REQUESTS 
6.16 BM#LOCK 



6.16 BMflLOCK 



This request sets a shared or exclusive lock on a,specified 
blocK of a file. The request and its parameters are: 

BMffLOCK (rba, status, opendesc, blocknum, locKopt, waitopt) 

The request is valid only for mass storage files and is 
intended to permit concurrent users of the file to coordinate 
their accesses to data. The affect of this request is to place a 
lock on a specific block (identified by the blocknum parameter) 
through an instance of open (identified by the opendesc 
parameter). 
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6.0 BLOCK MANAGEMENT REQUESTS 
6.17 BMffUNLOCK 

6.17 BM0UNLQCK 1 

2 

3 

This request clears a locK on a block that was previously 4 

set through this instance of open. The request and its 5 

parameters are: 6 

BM#UNLOCK (rba, status* opendesc* blocknum) 8 

9 

The request is a companion to the BM#LOCK request. If the 10 

blocKnum parameter is not null* the lock is cleared on a specific 11 

block. If the blocknum parameter is null* the locks are cleared 12 

on all blocks locked through this instance of open. 13 
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location - For tape and mass storage files, this field contains 
the LNS name of the Volume Set Control Block which describes 
the volume set on which this file resides. For unit record 
files, this field contains the LNS name of- the Oevice Control 
Block which describes the device on which this file resides* 
The default value is the name of the System Volume Set. 

owner - This field has meaning only for mass storage files and 
contains the user identifier under which the file is 
cataloged. The default value is the user identifier 
contained in the Job Control Block of the current Job. 

filename - This field contains the external name under which this 
file is cataloged or labeled. For mass storage files, the 
field may contain any character string up to 31 characters in 
length. For standard labeled tape files, the name may be up 
to 17 characters in length. The field has no meaning for 
tapes with nonstandard or no labels or for terminals and unit 
record devices. If the field is null and a name is required, 
the LNS name of the File Control Slock is supplied as 
default. 

generation - This field contains the four-byte generation number 
under which this file is cataloged or labeled and has meaning 
only for mass storage files and standard labeled tape files. 

expiration - This field contains the five byte expiration date 
for this file (in the form YYDDD) and has meaning only for 
mass storage files and standard labeled tape files. If the 
field is null and a date is required, the current date is 
supplied as default. 

fapname - This field contains the name of a File Access Procedure 
which is expected to run as a protected subsystem (the Data 
Base Control System, for example). If this field contains a 
name, linkage to the FAP will be made only through the Job 
Gate Table. If this field is null, FAP linkage will be 
attempted using the standard Loader search rules. There is 
no default value for this field. 

fapentry - This field contains the name of the entry point to a 
File Access Procedure. If this field is null, no FAP linkage 
will be attempted. There is no default value for this 
field. 

fapring - This field specifies the ring number at which the File 
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Access Procedure is expected to execute. If FAP linkage is 
attempted and the actual ring of execution is determined to 
be higher than this* the request is terminated abnormally. 
FAP linkage will rot occur and the file cannot be accessed. 
If the field is null* the actual ring obtained from the FAP 
linkage procedure is used. 

faDDararn - This field points to a parameter block through which 
the File Access Procedure expects to receive parameters from 
the user. The user may construct the parameter block in any 
accessible memory and is resoonsible for setting this field 
appropriately before issuing file management requests (except 
to define the file). There is no default value for this 
field. 

acclevel - This field defines the access level to be selected 
when the file is opened for processing. Tiree values are 
def inedt 

R - Record-level access 

3 - Block-level access 

S - Segment- 1 evel access (mass storage files only) 
If the field is null, record-level access is selected as 
default. 

fileorg - This field defines the organization of the file and may 
have one of four valuest 

I - Indexed organization 

R - Relative organization 

S - Sequential orgnization 

L - Library organization (for load modules only) 
If the field is null* Sequential organization is selected as 
def aul t. 

blocksize - This field defines the maximum block size (in bytes) 
for this file. If the field is null, the system page size is 
supplied as default. 

buffermode - This field defines the buffering mode for the file 
and has meaninq only if record-level access is also 
selected. The a 1 I owabl e va lues are: 

E ■- Explicit buffering is to be used 
' I - Implicit buffering is to be used 
Explicit buffering means that the record- I evel access 
procedures will use block- level access to the data. Implicit 
buffering means that the record-level access procedures will 
use Segment-Level access to the data. If the field is nullt 
explicit buffering is selected as default. 
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buffercount - This field defines the number of buffers to be used 
when the file is processed and also establishes the maximum 
number of simultaneously active block-level requests for any 
instance of open. The field does not have meaning for files 
which are accessed at segment level. If the field is null* 
an appropriate value (typically one to three) is selected as 
default at the time the file is opened. 

recordring -" This field specifies the highest ring from which 
record- I evel access requests may be issued. If the field 
contains a null value, the default values depend on the 
access level selected and are shown below: 

Record Level - ring of user or ring of FAP (if a 

FAP is defined) 
Block Level - ring one (record- 1 eve I access is 

prohibited) 
Segment Level - ring one (record- 1 eve I access is 

prohibited) 

blockring - This field specifies the highest ring from which 
block-level access requests may be issued. If the field 
contains a null value, the default valjes depend on the 
access level selected and are shown below! 

Record Level - ring of system record management 

procedures 
Block Level - ring of user or ring of FAP (if 

a FAP is defined) 
Segment Level - ring one (block-level access 

is prohibited) 



NOTE? If neither recordring nor blockring values are 
specified, the resulting defaults cause the file to be 
processed at the same access level each time it 
attached or opened. By specifying ring values, the 
owner can permit the file to be processed at different 
access levels. The owner must be aware, however, that 
while processing a file at block level that was 
created at record level is a potentially useful 
feature, the converse is not allowed. Note further 
th3t setfing all ring values to one effectively 
prohibits all access to the file, even by the system. 

writering - This field defines the highest write ring for files 
which allow segment-level access. If null, the 

system-supplied default depends upon the Access Level 
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selected for the file and is shown below. 

Record Level - ring of system record management 

procedures 
Block Level - ring of user or ring of FAP (if 

FAP is defined) 
Segment Level - ring of user or ring of FAP (if 

FAP is defined) 

readring - This field defines the highest read ring for files 
.which allow segment- 1 eve I access. If null, the 

systsm-supol i ed defaults are identical to those described for 
the writering field. 

NOTF: Since the wr it ering/readring fields. map directly to 
the R1/R2 fields defined by IPL hardware and since 
they also establish an execute bracket for segments 
which have execution enabled, the valjes suoplied for 
the two fields may not be lower than the ring from 
which the FM#CREATE_FILE or FM#REDEFINE_FILE requests 

are issued If th §_ f. n_e. h a s. LU2ra_r £_o_r ijani X3±io.jn. 

Since files having Library organization are the only 
files which can have "execute" usage selected* this 
prevents a user from directly creating an executable 
file which can execute at a ring lower than his 
current ring of execution. 



recformat - This field defines the record fo 
and may contain one of five values? 

F - fixed length records* no contro 
D - variable length records? each re 
a foui — byte control field 
decimal) the length of the r 
control fields. 
S - variable length spanned recor 
prefixed with a five byte contro 
a one-byte soanning indicator 
field. 
Y - variaole length records* each re 
a foui — oyte control field co 
binary sub-fields. 
U - undefined records* no control fi 
each record is equivalent to a b 
Record formats F, D* S and U conform to 
standards. Y format records are used by 
the default selection if the field is nu 
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I fields are oresent. 
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ecord including the 

ds * each record is 
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nd a four-byte length 
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ANSI tape interchange 
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This field defines the maximum record size (in .bytes) 
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for the file. If null, the default selection depends on the 
file organization and hardware tyDe but generally is equal to 
the block size less control field overhead. 



keyloc - This field 
organization. It 



is applicable to files with Indexed 
contains the location, relative to the 



ui vjctiii£.di iuu« xi mnidiiib I lie 1 utd i iuii , i emuve iu i ne 

start of a data record, of the first byte of the primary key 
(the first byte of a data record is numbered 1) and has no 
def au I t va I ue. 

keysize - This field is aDplicable only to files with Indexed 
organization. It contains the length, in bytes, of the 
primary key and has no default value. 

loading - This field is applicable only to files with Indexed 
organization. It specifies the loading percentage to be used 
when initially writing the file (a loading percentage of N 
means to fill all data blocks to approximately N percent of 
their maximum capacity) and has a default value of one 
hundred. 



comoression - This field has meaning only f 
organized files containing Y-format records wh 
< comoression. If the field con+ains the value 
compressed by the standard system algorithm 
them in block buffers. If the field contains 
null, records are not compressed. 

NOTE: This facility is intended p 
preparation of files which are to 
over low-speed serial communicati 
subsequent design information 
comoonents of the IPL hardware/s 
negates the anticipated use of th 
will be dropped. 



or sequential ly 
ich permit data 

Y, records are 
before placing 

the value N or 

rimarily for 
be transmitted 
on lines* If 
on related 
oftware system 
is facil ity, it 



spanoot - This field has meaning only for sequentially organized 
files containing Y-format records. If the field contains the 
value Y, records are permitted to span blocks. If the field 
contains the value N or null, records are not permitted to 
SDen blocks. 

NOTE! The major benefit of spanned records is that full 
utilization of space within a block is assumed. 
The major disadvantage is that records may not be 
updated if they are Dermitted to span blocks. 

filesize - This fiela soecifies the maximum size allowable for 
the file. It is expressed in units of blocks and has meaning 
only for mass storage files. If the field is null, an 
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installation-defined percentage is aDplied to the 
file size in order to allow subsequent expansion. 



initial 



expansion - This field specifies the expansion increment to be 
applied by the system whenever an implicit expansion of the 
file is required. It is expressed in units of blocks and has 
meaning only for mass storage files. If the field is null, 
an installation-defined default value is selected. 

vord - This field specifies the ordinal (within the volume set 
identified by the "location" field of This File Control 
Block) of the volume on which to restrict allocation whenever 
an implicit exDansion of the file is required. The field has 
meaning only for mass storage files. If the field contains 
all ones or is nu I I 1 all volumes of the volume set are 
considered candidates for allocation. 

verify - This field specifies whether write verification is to be 
used when the file is processed and has meaning only for mass 
storage files. A value of Y selects write verification a 
value of N or null suppresses write verification. 

userdata - This field contains a pointer to a user-supplied 
32-byte data area which will be saved with the cataloged 
description of the file. The field has meaning only for 
permanent mass storage files and has no default value. By 
supplying this pointer before the initial catalog entry is 
created for the file and supplying it before subsequently 
attaching the file? a facility roughly equivalent to user 
tape labels is provided. 

fapdata - this field contains a oointer to a FAP-suppI ied data 
area which will be saved with the cataloged description of 
the file. The field has meaning only for permanent mass 
storage files and has. no default value. By supplying this 
pointer before the initial catalog entry is created for the 
file and supplying it before subsequently attaching the filet 
the File Access Procedure is able to describe additional 
information it requires to orocess the file. 

sequence - This field defines the sequence number of this file on 
a multifile taoe volume set and has no default value. File 
sequence numbers are generated when files are initially 
written and are used for positioning when existing files are 
opened. 



section - This field SDecifies the current section 
multivolume tape file and has no defaul t value • 



number of a 
The field is 
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set to the value 0001 on the first section of the file and is 
incremented by one on each subsequent volume of the file. 

hdroption - This field specifies whether the standard four-byte 
block header is present and has meaning only for tape files 
processed through record-level access procedures. If the 
file contains the value N, block headers are suppressed on 
output and assumed not to be present on input. If the field 
contains the value Y or nu I I , the standard block header for 
sequential fields (containing a two-byte binary block length 
and a two-byte binary block sequence number) is generated on 
outout and checked on inout. 



bsnoption - This field specifies whether 
number contained in the standard block hea 
has meaning only for tape files 
record- level access procedures. If the f 
value N* the block seauence number in the 
to zero on outout and is not checked on in 
contains the value Y or null, block s 
generated on output and checked on inputs 
NOTES ProDer use of hdroption and bsnooti 
number of "industry standard" t 
processed directly by IPL re 
procedures. Non-standard codes 

record del imiting conventions mus 
handled in other ways. 
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linesize - This field specifies the maximum number of characters 

allowed on a single line and has meaning only for output to 

devices for which a "line" is defined. If null* an 

aopropriate default value is selected for the current 
hardware tyoe. 

oagesize - This field specifies the maximum number of lines on a 
single page and has meaning only for output to devices for 
which a "oagp" is defined. If null, an appropriate default 
value is selected for the current hardware type. 

formcnti - This field specifies the number of the forms control 
matrix to use when printing this file and has meaning only 
for printers which ODerate with a selectable forms control 
matrix. If the field contains all ones or is nul h the 
"standard" forms control matrix is selected. 

papercntl - This field specifies the number of the paper motion 
matrix to use when printing this file and has meaning only 
for printers which operate with a selectable paper motion 
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matrix. If the field contains all ones or is null? the 1 
"standard" paper motion matrix is selected. 2 

3 

linedelim - This field specifies the character to be interpreted 4 

as a line delimiter and has meaning only for input from 5 

keyboard devices. If null* an appropriate delimiter is 6 

selected for the current hardware tyoe. 7 

8 
backspace - This field specifies the character to be used for 9 
character deletion and has meaning only for input from 10 
teletype-like devices which transmit a character at a time. 11 
If nu I 1 1 an appropriate character is selected for the current 12 
hardware type. 13 

14 

msgdelim - This field specifies the character to be interpreted 15 

as end-of-message and has meaning only for terminal devices 16 

which operate in binary delimited mode. No default value is 17 

defined. 18 
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